.so ../bk-macros
.TH "bk fm3tool" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk fm3tool \- \*(BK three-way merge tool
.SH SYNOPSIS
.B bk fm3tool
.[OPTreq] \-o filename
.[B] \-fn
.OPTreq \-l local_rev
.OPTreq \-r remote_rev
.ARG file
.SH DESCRIPTION
.LP
.B bk fm3tool
is a three-way merge tool used for resolving conflicting changes
between two different versions of a file that have a common ancestor. 
Normally fm3tool is not run from the command line; it is started
during the resolve phase of a pull by responding with 
.Q f
at the merge prompt.
.LP
The purpose of this tool is to aid in the resolving of parallel
work that contains conflicts.
A conflict is defined as one or more lines that were added,
deleted, or modified in the local version of the file, at or
adjacent to one or more lines that were added, deleted, or
modified in the remote version of the file.
.LP
When the tool is started up, all of the changes that could be 
automerged have been automerged.
The rest of the changes are noted as
.DS
<<<<<<
UNMERGED
>>>>>>
.DE
.LP
in the merged file window (see below).
The tool's default behavior is to go to the first conflict and
wait for you to merge it.
Typically, you merge that conflict, go to the next
conflict, and repeat until done.
It is not necessary to merge the conflicts in order;
you may look at them all and merge them in any order.
You must merge all conflicts, however, before you may
save the file and exit.
.LP
When you are finished, you must save the file to complete
the merge.
.SH RUNNING OTHER GUI TOOLS
It might be useful to look at other information associated with
the changes.
The
.Q File
menu allows you to run several other tools:
.TP \fBcsettool\fP
.B revtool
This shows you the file history with the GCA, local,
and remote versions highlighted.
This is useful to see the progression of changes by selecting the
GCA and then diffing down one side and then the other side one
delta at a time.
.\" XXX - wouldn't it be cool to have a flash demo of this?
.tp
.B csettool
May be run on the additions, deletions, or both.
This can be useful when the context needed to resolve the conflict is 
contained elsewhere in the changeset that caused the conflict.
.SH SCREEN LAYOUT
.LP
When 
.B bk fm3tool
is started, there are six main areas on the screen.
Notice that information about the local repository is on the left
and remote repository is on the right.
.DS
+--------------------+------------------- +
| Local change info  | Remote change info |
+--------------------+--------------------+
| - GCA baseline     | - GCA baseline     |
| + Local change     | + Remote change    |
|                    |                    |
+--------------------+-----+--------------+
| Merge                    | Information  |
|                          |              |
|                          |              |
+--------------------------+--------------+
.DE
.TP "\fBRemote Change info\fP"
.B Local change info
Revision history for the local changes to the file
.tp
.B "Remote change info"
Revision history for the remote changes to the file
.tp
.B "Local diff"
Diff of local file versus the greatest common ancestor (GCA)
.tp
.B "Remote diff"
Diff of remote file versus the GCA
.tp
.B "Merge"
Result of the merge
.tp
.B "Information"
Informational messages and navigation controls
.LP 
As the tool moves from change to change, the top two windows will change 
to show revision history of the current highlighted change. 
The history shown for the deleted lines corresponds to the revisions
that did the deletions.
The annotation about which revisions added and deleted lines in the files
are shown by selecting View->Show Annotations.
.SH OPTIONS
.TP \-r\*<remote_rev\*>
.OPTreq \-o filename
save output to the specified file.
.tp
.B \-f 
force overwrite of existing file. By default fm3tool will
not overwrite an existing merge file.
.tp
.OPTreq \-l local_rev
the revision in the file to be considered the most recent local work.
.tp
.B \-n 
do not write any merged output, put the tool in readonly mode.
.tp
.OPTreq \-r remote_rev
the revision in the file to be considered the most recent remote work.
.SH HAND-EDITING
A merge conflict may be edited manually by single-clicking over a
highlighted diff in the merge window. The merge window will then
enter a special edit mode where you can make changes. 
To exit the edit mode, press
<\f(CWescape\fP> or click on area that divides the merge area from the areas
above it.
.SH COPY AND PASTE
When the tool is in edit mode, it is possible to select text from either diff
window and then copy them into the clipboard.  The text copied to the
clipboard is taken from the window with the active focus.  This can include
the merge window itself.
.LP
Pasting while focused in the left or right diff window will paste into the
merge window at the insertion cursor.  If the current block is UNMERGED, it
will be replaced with the contents of the clipboard.  Subsequent pastes
will be inserted after the last insertion.  Pasting while focused in the
merge window itself will paste at the insertion cursor with no special
action.
.SH KEYBOARD BINDINGS
fm3tool has two major modes: \*(lqmerging mode,\*(rq for
navigating through the diffs and conflicts and \*(lqediting
mode,\*(rq for hand-editing a merge.
Each of these modes has its own set of key bindings.
.SS MERGING MODE
.LP
.TP \fBShift-Right-Click\fP
.B Left-Click
Over a highlighted block in the upper windows, a left-click will append
the highlighted block of text to the current merge region in the merge
window. 
.B Left-Click
Over the merge window will enter hand-edit mode. See the section on
HAND EDITING, above.
.tp
.B Right-Click
Over a highlighted block in the upper windows, a right-click will
append the single line that was clicked on to the current merge region
in the merge window.
.tp
.B Shift-Left-Click
Works like a left click, but replaces the contents of the current
merge rather than adding on to it.
.tp 
.B Shift-Right-Click
Works like a right click, but replaces the contents of the current
merge with the line that was clicked on.
.tp
.B PageUp
Scroll up one page.
.tp
.B PageDown
Scroll down one page.
.tp
.B UpArrow
Scroll up one line.
.tp
.B DownArrow
Scroll down one line.
.tp
.B LeftArrow
Scroll left.
.tp
.B RightArrow
Scroll right.
.tp
.B <space>
move to the next conflict.
.tp
.B [
Move to previous difference.
.tp
.B ]
Move to next difference.
.tp
.B { 
Move to previous conflict.
.tp
.B }
Move to next conflict.
.tp
.B \-
Move to first difference.
.tp
.B \+
Move to last difference.
.tp
.B "x"
Toggle the display of the GCA.
.tp
.B "z"
Toggle the display of annotations.
.tp
.B "c"
Clears the current merge region.
.tp
.B "a"
Restores the auto-merge.
.tp
.B "m"
Restores the manual merge.
.tp
.B "s"
Saves the merge file.
.tp
.B "u"
Will undo the effects that the last mouse click had on the current
merge region.
.tp
.B "e"
This will move the focus to the merge edit window at the bottom and
put the tool in edit mode.
.tp
.B Control-q
Exit from fm3tool.
.SS EDITING MODE
.TP \fBShift-Right-Click\fP
.B <escape>
Exit edit mode
.tp
.B Control-a
move to start of line.
.tp
.B Control-e
move to end of line.
.tp
.B Control-n
move to next line.
.tp
.B Control-p
move to previous line.
.tp
.B Control-d
delete character under cursor.
.tp
.B Control-y
Redo the last undone change.
.tp
.B Control-z
Undo the last typed change.
.tp
.B UpArrow
Move the cursor up one line.
.tp
.B DownArrow
Move the cursor down one line.
.tp
.B LeftArrow
Move the cursor left one character.
.tp
.B RightArrow
Move the cursor right one character.
.tp
.B PageUp
Scroll up one page.
.tp
.B PageDown
Scroll down one page.
.SH "SEE ALSO"
.SA config-gui
.SA resolving
.SA smerge
.SA fmtool
.SH CATEGORY
.B GUI-tools
